'\" te
'\"! tbl|eqn | mmdoc
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp Jan 14 18:30
.ds Dm 01 colormate
.ds Xs 35305 5 colormaterial.gl
.TH GLCOLORMATERIAL 3G
.SH NAME
.B "glColorMaterial
\- cause a material color to track the current color

.SH C SPECIFICATION
void \f3glColorMaterial\fP(
GLenum \fIface\fP,
.nf
.ta \w'\f3void \fPglColorMaterial( 'u
	GLenum \fImode\fP )
.fi

.SH PARAMETERS
.TP \w'\f2face\fP\ \ 'u 
\f2face\fP
Specifies whether front,
back,
or both front and back material parameters should track the current color.
Accepted values are
\%\f3GL_FRONT\fP,
\%\f3GL_BACK\fP,
and \%\f3GL_FRONT_AND_BACK\fP.
The initial value is \%\f3GL_FRONT_AND_BACK\fP.
.TP
\f2mode\fP
Specifies which of several material parameters track the current color.
Accepted values are
\%\f3GL_EMISSION\fP,
\%\f3GL_AMBIENT\fP,
\%\f3GL_DIFFUSE\fP,
\%\f3GL_SPECULAR\fP,
and \%\f3GL_AMBIENT_AND_DIFFUSE\fP.
The initial value is \%\f3GL_AMBIENT_AND_DIFFUSE\fP.
.SH DESCRIPTION
\%\f3glColorMaterial\fP specifies which material parameters track the current color.
When \%\f3GL_COLOR_MATERIAL\fP is enabled,
the material parameter or parameters specified by \f2mode\fP,
of the material or materials specified by \f2face\fP,
track the current color at all times.
.P
To enable and disable \%\f3GL_COLOR_MATERIAL\fP, call
\%\f3glEnable\fP and \%\f3glDisable\fP with argument \%\f3GL_COLOR_MATERIAL\fP.
\%\f3GL_COLOR_MATERIAL\fP is initially disabled.
.SH NOTES
\%\f3glColorMaterial\fP makes it possible to change a subset of material parameters for each 
vertex using only the \%\f3glColor\fP command,
without calling \%\f3glMaterial\fP.
If only such a subset of parameters is to be specified for each
vertex, calling \%\f3glColorMaterial\fP is preferable to calling \%\f3glMaterial\fP.
.P
Call \%\f3glColorMaterial\fP before enabling \%\f3GL_COLOR_MATERIAL\fP.
.P
Calling \%\f3glDrawElements\fP, \%\f3glDrawArrays\fP, or \%\f3glDrawRangeElements\fP
may leave the current color indeterminate, if the color array is enabled.
If 
\%\f3glColorMaterial\fP is enabled while the current color is indeterminate, the 
lighting material state specified by \f2face\fP and \f2mode\fP is also indeterminate.
.P
If the GL version is 1.1 or greater, and \%\f3GL_COLOR_MATERIAL\fP is
enabled, evaluated color values affect the results of the lighting
equation as if the current color were being modified, but no change is
made to the tracking lighting parameter of the current color.
.SH ERRORS
\%\f3GL_INVALID_ENUM\fP is generated if \f2face\fP or \f2mode\fP is not an
accepted value.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glColorMaterial\fP is executed between
the execution of \%\f3glBegin\fP and the corresponding execution of \%\f3glEnd\fP.
.SH ASSOCIATED GETS
\%\f3glIsEnabled\fP with argument \%\f3GL_COLOR_MATERIAL\fP
.br
\%\f3glGet\fP with argument \%\f3GL_COLOR_MATERIAL_PARAMETER\fP
.br
\%\f3glGet\fP with argument \%\f3GL_COLOR_MATERIAL_FACE\fP
.SH SEE ALSO
\%\f3glColor(3G)\fP,
\%\f3glColorPointer(3G)\fP,
\%\f3glDrawArrays(3G)\fP,
\%\f3glDrawElements(3G)\fP,
\%\f3glDrawRangeElements(3G)\fP,
\%\f3glEnable(3G)\fP,
\%\f3glLight(3G)\fP,
\%\f3glLightModel(3G)\fP,
\%\f3glMaterial(3G)\fP
